package com.example.docmanagement.dto.request;

import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Pattern;
import jakarta.validation.constraints.Size;
import lombok.Data;

/**
 * 分类创建/更新请求 DTO
 * 用于创建新分类或更新现有分类
 * 支持树形结构（通过parentId建立父子关系）
 * 
 * 示例 JSON（顶级分类）:
 * {
 * "name": "编程语言",
 * "slug": "programming-languages",
 * "description": "各种编程语言的学习资料",
 * "icon": "code",
 * "parentId": null,
 * "sortOrder": 1
 * }
 * 
 * 示例 JSON（子分类）:
 * {
 * "name": "Java",
 * "slug": "java",
 * "description": "Java编程相关文档",
 * "icon": "java-logo",
 * "parentId": 1,
 * "sortOrder": 1
 * }
 */
@Data
@Schema(description = "分类创建/更新请求")
public class CategoryCreateRequest {

    /**
     * 分类名称（必填）
     * 分类的显示名称
     * 长度限制：1-100个字符
     * 示例："编程语言"、"Java"
     */
    @Schema(description = "分类名称", example = "编程语言", required = true, maxLength = 100)
    @NotBlank(message = "分类名称不能为空")
    @Size(max = 100, message = "分类名称长度不能超过 100 个字符")
    private String name;

    /**
     * 分类唯一标识符（必填）
     * 用于生成友好的URL路径
     * 格式要求：只能包含小写字母、数字和连字符
     * 长度限制：1-100个字符
     * 示例："programming-languages"、"java"
     */
    @Schema(description = "分类唯一标识符(slug)", example = "programming-languages", required = true, maxLength = 100, pattern = "^[a-z0-9-]+$")
    @NotBlank(message = "slug 不能为空")
    @Size(max = 100, message = "slug 长度不能超过 100 个字符")
    @Pattern(regexp = "^[a-z0-9-]+$", message = "slug 只能包含小写字母、数字和连字符")
    private String slug;

    /**
     * 分类描述（可选）
     * 详细描述该分类的用途和包含的内容
     * 示例："包含Java、Python、JavaScript等主流编程语言的学习资料"
     */
    @Schema(description = "分类描述", example = "包含Java、Python、JavaScript等主流编程语言的学习资料")
    private String description;

    /**
     * 分类图标（可选）
     * 图标名称或URL，用于前端显示
     * 示例："code"、"java-logo"、"https://example.com/icons/java.svg"
     */
    @Schema(description = "分类图标", example = "code")
    private String icon;

    /**
     * 父分类ID（可选）
     * 用于建立分类的层级关系
     * 为null或0表示顶级分类
     * 示例：1（表示这是ID为1的分类的子分类）
     * 注意：不能将自己设为父分类，会导致循环引用
     */
    @Schema(description = "父分类ID（null表示顶级分类）", example = "1")
    private Long parentId;

    /**
     * 排序顺序（可选）
     * 用于控制同级分类的显示顺序
     * 数值越小越靠前
     * 默认值：0
     * 示例：1, 2, 3...
     */
    @Schema(description = "排序顺序", example = "0", defaultValue = "0")
    private Integer sortOrder = 0;
}
